RESTful Routes
Part 1, Chapter 8
Next, let's set up three new routes, following RESTful best practices, with TDD:
| Endpoint | HTTP Method | CRUD Method | Result |
|---|---|---|---|
| /summaries | GET | READ | get all summaries |
| /summaries/:id | GET | READ | get a single summary |
| /summaries | POST | CREATE | add a summary |
For each, we'll:
- write a test
- run the test, to ensure it fails (red)
- write just enough code to get the test to pass (green)
- refactor (if necessary)
Let's start with the POST route.
POST Route
We'll break from the normal TDD flow for this first route in order to establish the pattern that we'll use for the remaining routes.
Code
Create a new file called summaries.py in the "project/app/api" folder:
# project/app/api/summaries.py
from fastapi import APIRouter, HTTPException
from app.api import crud
from app.models.pydantic import SummaryPayloadSchema, SummaryResponseSchema
router = APIRouter()
@router.post("/", response_model=SummaryResponseSchema, status_code=201)
async def create_summary(payload: SummaryPayloadSchema) -> SummaryResponseSchema:
summary_id = await crud.post(payload)
response_object = {
"id": summary_id,
"url": payload.url
}
return response_object
Here, we defined a handler that expects a payload, payload: SummaryPayloadSchema, with a URL.
Essentially, when the route is hit with a POST request, FastAPI will read the body of the request and validate the data:
- If valid, the data will be available in the payload
parameter. FastAPI also generates JSON Schema definitions that are then used to automatically generate the OpenAPI schema and the API documentation. - If invalid, an error is immediately returned.
Review the Request Body docs for more info.
It's worth noting that we used the async declaration here since the database communication will be asynchronous. In other words, there are no blocking I/O operations in the handler.
Next, create a new file called crud.py in the "project/app/api" folder:
# project/app/api/crud.py
from app.models.pydantic import SummaryPayloadSchema
from app.models.tortoise import TextSummary
async def post(payload: SummaryPayloadSchema) -> int:
summary = TextSummary(
url=payload.url,
summary="dummy summary",
)
await summary.save()
return summary.id
We added a utility function called post for creating new summaries that takes a payload object and then:
- Creates a new
TextSummaryinstance - Returns the generated ID
Next, we need to define a new pydantic model for use as the response_model:
@router.post("/", response_model=SummaryResponseSchema, status_code=201)
Update pydantic.py like so:
# project/app/models/pydantic.py
from pydantic import BaseModel
class SummaryPayloadSchema(BaseModel):
url: str
class SummaryResponseSchema(SummaryPayloadSchema):
id: int
The SummaryResponseSchema model inherits from the SummaryPayloadSchema model, adding an id field.
Wire up the new router in main.py:
# project/app/main.py
import logging
from fastapi import FastAPI
from app.api import ping, summaries # updated
from app.db import init_db
log = logging.getLogger("uvicorn")
def create_application() -> FastAPI:
application = FastAPI()
application.include_router(ping.router)
application.include_router(summaries.router, prefix="/summaries", tags=["summaries"]) # new
return application
app = create_application()
@app.on_event("startup")
async def startup_event():
log.info("Starting up...")
init_db(app)
@app.on_event("shutdown")
async def shutdown_event():
log.info("Shutting down...")
Take note of the prefix URL along with the "summaries" tag, which will be applied to the OpenAPI schema (for grouping operations).
Test it out with curl or HTTPie:
$ http --json POST http://localhost:8004/summaries/ url=http://testdriven.io
You should see:
HTTP/1.1 201 Created
content-length: 37
content-type: application/json
date: Mon, 27 Dec 2021 14:28:49 GMT
server: uvicorn
{
"id": 1,
"url": "http://testdriven.io"
}
You can also interact with the endpoint at http://localhost:8004/docs.
Test
First, add a new file called test_summaries.py to "project/tests". Then, add the following test:
# project/tests/test_summaries.py
import json
import pytest
def test_create_summary(test_app_with_db):
response = test_app_with_db.post("/summaries/", data=json.dumps({"url": "https://foo.bar"}))
assert response.status_code == 201
assert response.json()["url"] == "https://foo.bar"
Add the new fixture to conftest.py:
import os
import pytest
from starlette.testclient import TestClient
from app.main import create_application
from app.config import get_settings, Settings
def get_settings_override():
return Settings(testing=1, database_url=os.environ.get("DATABASE_TEST_URL"))
@pytest.fixture(scope="module")
def test_app():
# set up
app = create_application()
app.dependency_overrides[get_settings] = get_settings_override
with TestClient(app) as test_client:
# testing
yield test_client
# tear down
# new
@pytest.fixture(scope="module")
def test_app_with_db():
# set up
app = create_application()
app.dependency_overrides[get_settings] = get_settings_override
register_tortoise(
app,
db_url=os.environ.get("DATABASE_TEST_URL"),
modules={"models": ["app.models.tortoise"]},
generate_schemas=True,
add_exception_handlers=True,
)
with TestClient(app) as test_client:
# testing
yield test_client
# tear down
Add the import as well:
from tortoise.contrib.fastapi import register_tortoise
Run the tests:
$ docker-compose exec web python -m pytest
=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0
collected 2 items
tests/test_ping.py . [ 50%]
tests/test_summaries.py . [100%]
================================ 2 passed in 0.19s ================================
Did a warning get outputted? Pass
-p no:warningson the command-line in to disable them.
This test covers the happy path. What about the exception path?
Add a new test:
# project/tests/test_summaries.py
import json
import pytest
def test_create_summary(test_app_with_db):
response = test_app_with_db.post("/summaries/", data=json.dumps({"url": "https://foo.bar"}))
assert response.status_code == 201
assert response.json()["url"] == "https://foo.bar"
def test_create_summaries_invalid_json(test_app):
response = test_app.post("/summaries/", data=json.dumps({}))
assert response.status_code == 422
assert response.json() == {
"detail": [
{
"loc": ["body", "url"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
It should pass.
With that, we can configure the remaining CRUD routes using Test-Driven Development.
├── .gitignore
├── docker-compose.yml
└── project
├── .dockerignore
├── Dockerfile
├── app
│ ├── __init__.py
│ ├── api
│ │ ├── __init__.py
│ │ ├── crud.py
│ │ ├── ping.py
│ │ └── summaries.py
│ ├── config.py
│ ├── db.py
│ ├── main.py
│ └── models
│ ├── __init__.py
│ ├── pydantic.py
│ └── tortoise.py
├── db
│ ├── Dockerfile
│ └── create.sql
├── entrypoint.sh
├── migrations
│ └── models
│ └── 0_20211227001140_init.sql
├── pyproject.toml
├── requirements.txt
└── tests
├── __init__.py
├── conftest.py
├── test_ping.py
└── test_summaries.py
GET single summary Route
Start with a test:
def test_read_summary(test_app_with_db):
response = test_app_with_db.post("/summaries/", data=json.dumps({"url": "https://foo.bar"}))
summary_id = response.json()["id"]
response = test_app_with_db.get(f"/summaries/{summary_id}/")
assert response.status_code == 200
response_dict = response.json()
assert response_dict["id"] == summary_id
assert response_dict["url"] == "https://foo.bar"
assert response_dict["summary"]
assert response_dict["created_at"]
Ensure the test fails:
> assert response.status_code == 200
E assert 404 == 200
E + where 404 = <Response [404]>.status_code
Add the following handler:
@router.get("/{id}/", response_model=SummarySchema)
async def read_summary(id: int) -> SummarySchema:
summary = await crud.get(id)
return summary
Here, instead of taking a payload, the handler requires an id, an integer, which will come from the path -- i.e., /summaries/1/.
Add the get utility function to crud.py:
async def get(id: int) -> Union[dict, None]:
summary = await TextSummary.filter(id=id).first().values()
if summary:
return summary
return None
Add the import:
from typing import Union
Here, we used the values method to create a ValuesQuery object. Then, if the TextSummary exists, we returned it as a dict.
Union[dict, None]is equivalent toOptional[dict], so feel free to update this if you preferOptionaloverUnion.
Next, update project/app/models/tortoise.py to generate a pydantic model from the Tortoise model:
# project/app/models/tortoise.py
from tortoise import fields, models
from tortoise.contrib.pydantic import pydantic_model_creator # new
class TextSummary(models.Model):
url = fields.TextField()
summary = fields.TextField()
created_at = fields.DatetimeField(auto_now_add=True)
def __str__(self):
return self.url
SummarySchema = pydantic_model_creator(TextSummary) # new
Import SummarySchema into project/app/api/summaries.py:
from app.models.tortoise import SummarySchema
Ensure the tests pass:
$ docker-compose exec web python -m pytest
=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0
collected 4 items
tests/test_ping.py . [ 25%]
tests/test_summaries.py ... [100%]
================================ 4 passed in 0.20s ================================
What if the summary ID doesn't exist?
Add a new test:
def test_read_summary_incorrect_id(test_app_with_db):
response = test_app_with_db.get("/summaries/999/")
assert response.status_code == 404
assert response.json()["detail"] == "Summary not found"
It should fail:
> assert response.status_code == 404
E assert 200 == 404
E + where 200 = <Response [200]>.status_code
Update the code:
@router.get("/{id}/", response_model=SummarySchema)
async def read_summary(id: int) -> SummarySchema:
summary = await crud.get(id)
if not summary:
raise HTTPException(status_code=404, detail="Summary not found")
return summary
It should now pass:
=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0
collected 5 items
tests/test_ping.py . [ 20%]
tests/test_summaries.py .... [100%]
================================ 5 passed in 0.21s ================================
Before moving on, manually test the new endpoint in the browser, with curl or HTTPie, and/or via the API documentation.
GET all summaries Route
Again, let's start with a test:
def test_read_all_summaries(test_app_with_db):
response = test_app_with_db.post("/summaries/", data=json.dumps({"url": "https://foo.bar"}))
summary_id = response.json()["id"]
response = test_app_with_db.get("/summaries/")
assert response.status_code == 200
response_list = response.json()
assert len(list(filter(lambda d: d["id"] == summary_id, response_list))) == 1
Make sure it fails. Then add the handler:
@router.get("/", response_model=List[SummarySchema])
async def read_all_summaries() -> List[SummarySchema]:
return await crud.get_all()
Import List from Python's typing module:
from typing import List
The response_model is a List with a SummarySchema subtype.
Add the CRUD util:
async def get_all() -> List:
summaries = await TextSummary.all().values()
return summaries
Update the import:
from typing import Union, List
Does the test past?
=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0
collected 6 items
tests/test_ping.py . [ 16%]
tests/test_summaries.py ..... [100%]
================================ 6 passed in 0.22s ================================
Manually test this endpoint as well.
Selecting Tests
You can select specific tests to run using substring matching.
For example, to run all tests that have ping in their names:
$ docker-compose exec web python -m pytest -k ping
=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0
collected 6 items / 5 deselected / 1 selected
tests/test_ping.py . [100%]
========================= 1 passed, 5 deselected in 0.14s =========================
So, you can see that the single test in test_ping.py ran (and passed) while the five tests in test_summaries.py were skipped.
Which test(s) will run when you run this command:
$ docker-compose exec web python -m pytest -k read
Pytest Commands
Before moving on, let's review some useful pytest commands:
# normal run
$ docker-compose exec web python -m pytest
# disable warnings
$ docker-compose exec web python -m pytest -p no:warnings
# run only the last failed tests
$ docker-compose exec web python -m pytest --lf
# run only the tests with names that match the string expression
$ docker-compose exec web python -m pytest -k "summary and not test_read_summary"
# stop the test session after the first failure
$ docker-compose exec web python -m pytest -x
# enter PDB after first failure then end the test session
$ docker-compose exec web python -m pytest -x --pdb
# stop the test run after two failures
$ docker-compose exec web python -m pytest --maxfail=2
# show local variables in tracebacks
$ docker-compose exec web python -m pytest -l
# list the 2 slowest tests
$ docker-compose exec web python -m pytest --durations=2
✓ Mark as Completed